# 基础 API

## useNavigate

返回一个用于在路由间进行编程式导航的函数的钩子。

**类型：**

```ts
useNavigate(): (href: string, options?: NavigateOptions) => void
```

**参数：**

- `href`: 目标路径，可包含查询字符串
- `options`: 可选配置
  - `relative`: 如果为 `false`，导航到绝对路径，忽略相对基准。默认为 `true`
  - `replace`: 如果为 `true`，替换当前历史记录
  - `noScroll`: 如果为 `true`，阻止导航时滚动到顶部
  - `state`: 可选的状态对象，会被传递给 `history.state`。默认为 `null`

**示例：**

```jsx
function NavigationComponent() {
  const navigate = useNavigate()

  return (
    <>
      <button onClick={() => navigate('/')}>首页</button>
      <button onClick={() => navigate('/products', { relative: false })}>
        产品
      </button>
      <button onClick={() => navigate('/login', { replace: true })}>
        登录
      </button>
      <button onClick={() => navigate('/details', { noScroll: true })}>
        查看详情（不滚动）
      </button>
      <button onClick={() => navigate('/search?q=zess&page=1')}>
        搜索 Zess（第1页）
      </button>
      <button onClick={() => navigate('/checkout', { state: { userId: 1 } })}>
        前往结账
      </button>
    </>
  )
}
```

## useSearchParams

提供对搜索参数访问权限以及更新这些参数的函数的钩子。

**类型：**

```ts
useSearchParams(): [SearchParams, (params: Record<string, any>, options?: SearchParamsOptions) => void]
```

**返回值：** 包含以下内容的数组

- `searchParams`: 响应式对象，包含当前搜索参数，当 `location.search` 更改或通过 `setSearchParams` 修改时会自动更新
- `setSearchParams`: 更新搜索参数的函数
  - `params`: 要与现有参数合并的搜索参数。将属性值设置为 `undefined`、`null` 或空字符串会移除该属性
  - `options`: 可选的配置对象
    - `replace`: 可选标志，用于替换当前历史记录条目而不是添加新条目
    - `state`: 可选的状态对象，会被传递给 `history.state`。默认为 `null`

**示例：**

```jsx
function ProductFilter() {
  const [searchParams, setSearchParams] = useSearchParams()
  const setCategory = (category) => setSearchParams({ category })
  const search = (keyword, searchType) => {
    setSearchParams(
      { keyword },
      {
        replace: true,
        state: { searchType },
      },
    )
  }
  const clearFilters = () => {
    setSearchParams({ category: undefined, keyword: undefined })
  }

  return (
    <div>
      <p>当前分类: {searchParams.category || '全部'}</p>
      <p>搜索关键词: {searchParams.keyword || '无'}</p>
      <button onClick={() => setCategory('shoes')}>设置分类</button>
      <button onClick={() => search('sale', 'quick')}>按类型搜索</button>
      <button onClick={clearFilters}>清除筛选</button>
    </div>
  )
}
```

## useBeforeLeave

注册一个在离开当前路由前调用的监听器的钩子。这允许您拦截导航尝试并可能阻止它们，例如，警告用户有关未保存的更改。

**类型：**

```ts
useBeforeLeave(listener: RouteGuardListener): void
```

**参数：**

- `listener`: 当尝试从当前路由导航离开时调用的函数，接收 `RouteGuardEvent` 对象
  - `event`: 路由守卫事件对象，包含：
    - `to`: 要导航到的目标路径
    - `from`: 正在导航离开的当前路径
    - `options`: 导航选项，包括 `relative`、`replace` 和 `noScroll`
    - `defaultPrevented`: 布尔值，指示导航是否已被阻止
    - `preventDefault`: 阻止导航的函数
    - `retry`: 稍后重试导航的函数，带有可选的 `force` 参数以绕过守卫

**示例：**

```jsx
function FormEditor() {
  const [hasUnsavedChanges, setHasUnsavedChanges] = useSignal(false)
  useBeforeLeave((event) => {
    if (hasUnsavedChanges()) {
      const confirmed = window.confirm('您有未保存的更改。确定要离开吗？')
      if (!confirmed) {
        event.preventDefault()
      }
    }
  })

  return (
    <div>
      <input type="text" onChange={() => setHasUnsavedChanges(true)} />
      <button onClick={() => setHasUnsavedChanges(false)}>保存</button>
    </div>
  )
}
```

## useLocation

返回一个响应式 `Location` 对象的钩子，该对象包含当前 URL 的相关信息。当 URL 变化时，此对象会自动更新。

**类型：**

```ts
useLocation(): Location
```

**返回值：** 一个带有 `pathname` 和其他属性的响应式 `Location` 对象

- `pathname`: URL 的路径部分，不包含查询字符串
- `search`: URL 的查询字符串部分
- `hash`: URL 的哈希部分，包含 `#` 符号
- `state`: 与当前历史记录条目关联的状态对象，通过 `useNavigate` 或 `<Link>` 组件传递
- `query`: 包含 URL 所有查询参数的响应式对象

**示例：**

```jsx
function LocationDisplay() {
  const location = useLocation()

  return (
    <div>
      <h2>当前位置信息</h2>
      <p>路径: {location.pathname}</p>
      <p>查询字符串: {location.search}</p>
      <p>哈希值: {location.hash}</p>
      <p>状态: {JSON.stringify(location.state)}</p>
      <p>查询参数: {JSON.stringify(location.query)}</p>
    </div>
  )
}
```
